<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html version="4.01"><head><title>[retawq] URL Schemes</title></head>
<body text="#000000" bgcolor="#cccccc" link="#0000ff" vlink="#551a8b"
alink="#551a8b" lang="en">
<center><b><font size="+2">retawq Documentation</font><br><font size="+1">URL
Schemes</font></b></center>

<p><a name="intro"></a><b>Introduction</b></p>

<p>retawq supports several types ("schemes") of URLs. The scheme specifies how
a resource is accessed, e.g. which network protocol is used. This page lists a
few examples of currently supported URLs and general notes to show what's
possible and how retawq interprets URLs, including some "magic assumptions"
(built-in defaults) for URLs which don't contain an explicit scheme.</p>

<p>retawq can currently handle the following schemes: "http", "https" (if
enabled), "ftp", "ftps" (if enabled), "news"/"nntp" (if enabled), "finger",
"file"/"local", "local-cgi" (if enabled), "about". The scheme "local-cgi" is
retawq-specific; a similar feature is available in Lynx with the scheme
"lynxcgi". The scheme "about" is available in several other web browsers, but
with different URLs.</p>

<p>Since the "U" in "URL" means "uniform", retawq tries to apply the general
URL format "scheme://username:password@hostname:portnumber/path?query#fragment"
to all URLs as far as possible. One little disadvantage is that local
file/directory/script names can't contain the special characters "?" and "#",
because these characters are interpreted as the beginning of query and fragment
parts, respectively (and the query part is actually used, e.g. for local
directory sorting options).</p>

<p>The "#fragment" part of a URL is recognized and removed, but not yet
handled.</p>

<p><a name="http"></a><b>HTTP</b></p>

<p>"http://foo.org/" - receive the document "/" (usually this means
"/index.html" or "/index.htm") from the server "foo.org" via HTTP; the default
HTTP port (80) is used.</p>
<p>"foo.org" - the same unless you have a file or directory with that name in
the current directory on your local computer</p>
<p>"www.foo.org" - if no explicit scheme is given and the domain name begins
with "www.", the HTTP scheme is assumed, no matter whether a file or directory
with that name exists on your local computer</p>
<p>"http://foo.org:42/bar.html" - receive the document "/bar.html" from the
server "foo.org" via HTTP; the non-standard port 42 is used.</p>
<p>"http://foo.org/cgi-bin/bar.cgi?whatever" - send the query "whatever" to the
CGI script "/cgi-bin/bar.cgi" on the HTTP server "foo.org" and receive the
resulting document</p>

<p><a name="https"></a><b>https</b></p>

<p>The scheme "https" works very much like "http", except that <a
href="tls.html">TLS/SSL</a> (which must have been enabled) is used for secure
network communications.</p>

<p><a name="ftp"></a><b>FTP</b></p>

<p>"ftp://ftp.foo.org/" - receive the top-level FTP directory ("/") from the
FTP server ftp.foo.org; the default FTP port (21) is used.</p>
<p>"ftp.foo.org" - the same; if no explicit scheme is given and the domain name
begins with "ftp.", the FTP scheme is assumed.</p>
<p>"ftp://ftp.foo.org:42/bar/" - receive the directory "/bar" from the server
ftp.foo.org via FTP; the non-standard port 42 is used.</p>
<p>"ftp://username:password@ftp.foo.org/home/user/" - receive the directory
"/home/user" from the server ftp.foo.org via FTP, logging in as user "username"
with password "password"; if you need to log in frequently, consider using the
<a href="rtconfig.html">run-time configuration option</a> "ftp-login".</p>

<p><a name="ftps"></a><b>ftps</b></p>

<p>The scheme "ftps" works very much like "ftp", except that <a
href="tls.html">TLS/SSL</a> (which must have been enabled) is used for secure
network communications.</p>

<p>Some server programs can only protect the control connection, not the data
connection; please read about the <a href="rtconfig.html">run-time
configuration option</a> "ftps-method", especially the method specifier
"authtls-dataclear".</p>

<p><a name="news"></a><b>News/NNTP</b></p>

<p>These schemes only work if the <a href="ctconfig.html">compile-time
configuration option</a> OPTION_NEWS has been enabled. The scheme "nntp" is
handled in exactly the same way as the scheme "news"; the different scheme
names only exist due to historical differences in protocol specifications.</p>
<p>If the URL doesn't contain an explicit domain name, retawq uses the default
name as configured with the <a href="rtconfig.html">run-time configuration
option</a> "news-server-default". (If no explicit name is given and no default
name is configured, you get a "Hostname missing" error.) Some of the following
examples assume that a default name has been configured, just to improve
readability.</p>

<p>"news://news.foo.org/" - show a list of all news groups which are available
on the server "news.foo.org"; the default NNTP port (119) is used.</p>
<p>"news.foo.org" - the same; if no explicit scheme is given and the domain
name begins with "news.", the news scheme is assumed.</p>
<p>"news:alt.fan.douglas-adams" - show an index of all articles in the news
group "alt.fan.douglas-adams" on the default news server, latest first</p>
<p>"news:alt.fan.douglas-adams/100-200" - similar, but the index only shows the
articles with the numbers 100 to 200 (as far as they exist)</p>
<p>"news:alt.fan.douglas-adams/100" - show the article (header and body) with
the number 100 in the news group "alt.fan.douglas-adams" on the default news
server</p>
<p>"news:foo@bar.com" - show the article (header and body) with the so-called
<i>message identifier</i> "foo@bar.com"; the message identifier of an article
"should" be world-wide unique across all servers and groups, so this is the
preferred form of referencing (e.g. when putting a link on a web page) a news
article; in contrast to message identifiers, the above combinations of group
names and plain article numbers aren't unique because different servers might
use different numbers for the same article and vice versa. - Message
identifiers can be recognized by the presence of an "@" character.</p>

<p><a name="finger"></a><b>Finger</b></p>

<p>"finger://username@foo.org" - show information about the user "username" on
the server "foo.org"; the default finger port (79) is used.</p>
<p>"finger://username@foo.org:42" - show information about the user "username"
on the server "foo.org"; the non-standard port 42 is used.</p>
<p>"finger://finger.kernel.org" - show information about current Linux kernel
versions</p>

<p><a name="local"></a><b>Local Files and Directories</b></p>

<p>"local:/home/" - list the contents of the local directory "/home"</p>
<p>"/home" - the same; if no explicit scheme is given and the URL begins with
"/", "~/" or "./", a local file/directory is assumed</p>
<p>"local:/home/foo/bar.html" - show the local file "/home/foo/bar.html"</p>
<p>"local:~/foo/bar.html" - show the local file "foo/bar.html" in the user's
local home directory (depending on the environment variable "HOME"); normally
this results in an absolute path like
"/home/<i>your_home</i>/foo/bar.html".</p>
<p>"local:/home/my_home?sort=tS" - show the contents of the local directory
"/home/my_home", sorted by file type (lowercase "t", ascending) and size
(uppercase "S", descending); cf. the <a href="rtconfig.html">run-time
configuration option</a> "local-dir-sort" for more information.</p>
<p>"local:foo/bar.html" - show the local file "foo/bar.html" in the "current"
directory; this is normally the directory in which you were when you launched
retawq.</p>

<p>Most other browsers use the scheme "file" instead of "local"; with retawq,
you can use both of them, and they have the same meaning; "local" is just
preferred because "file" might seem as if you could only access files and no
directories...</p>

<p>retawq only reads regular files and directories; for example, it doesn't try
to read from device nodes like "/dev/zero". It shows "Document empty" messages
if the operating system erroneously reports a file size 0, which might e.g. be
the case for system-generated files inside the directory "/proc".</p>

<p><a name="local-cgi"></a><b>Local CGI Scripts</b></p>

<p>"local-cgi:/usr/cgi-bin/script.cgi" - launch the script
"/usr/cgi-bin/script.cgi" on the local computer and show its output</p>

<p>For security reasons, this scheme only works if the <a
href="ctconfig.html">compile-time configuration option</a> OPTION_LOCAL_CGI has
been enabled, and scripts are only launched as the <a
href="rtconfig.html">run-time configuration option</a> "local-cgi" explicitly
allows it.</p>

<p>retawq currently uses version 1.1 of the Common Gateway Interface (<a
href="http://www.w3.org/CGI/">CGI</a>) specification to launch scripts. There's
a <a href="example-script.cgi">script example</a> available.</p>

<p><a name="about"></a><b>about</b></p>

<p>"about:retawq" - show information about retawq and possibly about used
libraries; this is normally shown when you start retawq in curses-like <a
href="runmode.html">runmode</a> without providing URLs on the
command-line.</p>

<p>"about:" - the same</p>

<p>"about:help" - a quick pointer to locations where documentation is
available; the link for the local URL only works if you installed the package
properly, e.g. with "make install".</p>

<p>"about:activity" - show some raw information about retawq's current
activity, e.g. about the open connections to servers; this doesn't yet look
nice and you have to reload it manually to get updated information, but it
might be useful sometimes, especially when downloads are running</p>

<p>"about:hostinfo" - show some raw information about hosts which have been
visited or whose names have been looked up in the DNS (Domain Name System);
this information was mostly intended for debugging, but it might sometimes be
generally useful to find out the IP addresses of certain hosts</p>

<p>"about:ctconfig" - show information about the actual values of <a
href="ctconfig.html">compile-time configuration options</a> which were used
when retawq was built</p>

<p>"about:birtcfg" - show the text of a built-in <a
href="rtconfig.html">run-time configuration</a>; cf. the <a
href="ctconfig.html">compile-time configuration option</a> OPTION_BIRTCFG.</p>

<p><hr>This documentation file is part of version 0.2.6c of <a
href="http://retawq.sourceforge.net/">retawq</a>, a network client created by
<span lang="de">Arne Thoma&szlig;en</span>. retawq is basically released under
certain versions of the GNU General Public License and WITHOUT ANY WARRANTY.
Copyright (C) 2001-2006 <a href="mailto:arne@arne-thomassen.de"><span
lang="de">Arne Thoma&szlig;en</span></a>.</p>
</body></html>
